Fix fill-value handling across Omega so inactive parts of arrays hold well-defined, NetCDF-standard fill values instead of uninitialized memory or inconsistent local sentinels, initialize the Kokkos arrays backing fields at attach time, and mask cell, edge, and vertex state fields to their active layers after initialization. Based on the companion PR that fixes biharmonic velocity mixing at boundary vertices (peeled out of this branch in #456).

Motivation

Omega fields declared their fill values locally in each module with inconsistent values (-9.99e30, -9.99E+30, -999, etc.) that did not match the NetCDF-C standard. More critically, the Kokkos arrays backing those fields were never explicitly initialized: inactive ocean layers (outside a column's active range) held uninitialized memory rather than a well-defined sentinel, so output files contained garbage rather than a recognizable fill value. Switching from zero-initialization to fill-value initialization also exposed a latent class of bugs where edge and boundary-layer fields assumed zero at mesh boundaries, producing corrupted tendencies when those layers were no longer zero by default. This change standardizes the fill-value constants, auto-fills arrays at attach time, and masks cell, edge, and vertex state fields to their valid layer ranges (with the correct per-geometry boundary treatment) after IC/restart read.

Summary

Fix fill-value handling across Omega:

• Add components/omega/src/base/FillValues.h with centralized constexpr fill value constants (FillValueI4, FillValueI8, FillValueR4, FillValueR8, FillValueReal) that exactly match the NetCDF-C NC_FILL_* / SCORPIO PIO_FILL_* values. A type-indexed variable template FillValue<T> provides the primary interface.
• Remove the FillValue argument from Field::create() (and from Tracers::define() / TracerDefs.inc). The fill value is now deduced automatically from the array's element type at attachData() time.
• Add auto-fill to Field::attachData<T>(): a private fillWithValue<T>() helper calls Kokkos::deep_copy(InDataArray, FillValue<ValType>) and records the value in FieldMeta["_FillValue"] (the CF/NetCDF standard attribute). An optional FillOnAttach = false argument covers the cases where attachData() is called only to re-point a field at an already-computed array (time-level updates in OceanState and Tracers, and the IO time-coordinate attach/assign ordering).
• Add layer-masking helpers to VertCoord: zeroEdgeField and applyEdgeLayerMask for edge fields (three-zone), and applyCellLayerMask and applyVertexLayerMask for cell and vertex fields (two-zone). Cell and vertex fields have no zeroed boundary zone: a cell layer is simply active or inactive, and a boundary vertex with one or more active surrounding cells holds valid, generally non-zero data.
• Add OceanState::applyLayerMasks(TimeLevel), a single entry point that applies applyEdgeLayerMask to NormalVelocity and applyCellLayerMask to PseudoThickness, Temperature, and Salinity; it is called from OceanInit after the IC/restart read. NormalVelocity is additionally masked in the OceanState constructor and after each updateVelocityByTend step in the time stepper to keep the three-zone invariant throughout the run.
• Call zeroEdgeField on NormalVelocityTend and VelocityDel2Aux.Del2Edge at the start of each tendency computation, so boundary layers show 0 rather than FillValueReal as required for flux-type edge fields.
• Read MinLayerCell, MaxLayerCell, BottomGeomDepth, RefPseudoThickness, and VertCoordMovementWeights from the InitialVertCoord stream, with robust fill-value-count detection so a missing or unreadable variable falls back to a sensible default (e.g. MinLayerCell at the surface, MaxLayerCell at NVertLayers) instead of propagating fill values into the vertical-coordinate setup.
• Fix VertAdv::computeVerticalPseudoVelocity (DivHU): clamp the inner edge loop to K <= MaxLayerEdgeTop(JEdge) to avoid reading fill values from edges shallower than the owning cell.
• Add FillValueTest CTest (8 MPI tasks) with six subtests: fill-constant equality with NC_FILL_*, attachData auto-fill, inactive cell-layer fill after VertCoord initialization, the three-zone NormalVelocity invariant after IC read and applyEdgeLayerMask, the two-zone applyCellLayerMask pattern, and the two-zone applyVertexLayerMask pattern.
• Add the design document components/omega/doc/design/FillValues.md and update the Field, Tracer, and VertCoord developer/user guides to describe fill values and layer masking.

Layer masking approach

Fields span layers [0, NVertLayers), but the valid extent of each cell, edge, or vertex is set by the active layers of the neighboring cells. The masking helpers enforce this per geometry.

Edge fields use four per-edge layer indices (stored in VertCoord) that define three zones:

Zone 1 — fully inactive (K < MinLayerEdgeTop or K > MaxLayerEdgeBot): both neighboring cells are inactive at this layer. These layers hold FillValueReal and must never participate in any computation.

Zone 2 — boundary layer (MinLayerEdgeTop <= K < MinLayerEdgeBot or MaxLayerEdgeTop < K <= MaxLayerEdgeBot): exactly one neighbor is active. For flux-type edge fields (NormalVelocity, NormalVelocityTend, Del2Edge) the physically correct value is 0 because no flux crosses a solid boundary. For thickness-interpolated fields (MeanPseudoThickEdge, FluxPseudoThickEdge) the value is genuinely undefined and retains FillValueReal.

Zone 3 — active (MinLayerEdgeBot <= K <= MaxLayerEdgeTop): both neighbors are active; the field carries a normally computed value.

VertCoord::zeroEdgeField sets zones 1+2 to 0 (used at the start of each tendency step for flux fields that are recomputed each step, where the attachData fill cannot be relied on). VertCoord::applyEdgeLayerMask imposes the full three-zone pattern (zone 1 → fill, zone 2 → 0, zone 3 → unchanged) and is applied after IC/restart read and after each velocity tendency update.

Cell and vertex fields use a simpler two-zone pattern, because there is no flux-through-boundary condition to enforce. applyCellLayerMask sets layers outside [MinLayerCell, MaxLayerCell] to FillValueReal and leaves the active range unchanged. applyVertexLayerMask sets layers outside [MinLayerVertexTop, MaxLayerVertexBot] to FillValueReal and leaves the active range unchanged; unlike edges there is no zeroed boundary zone, since a boundary vertex adjacent to at least one active cell holds valid, generally non-zero data.

Checklist

• Documentation:
  • Design document has been generated and added to the docs
  • User's Guide has been updated
  • Developer's Guide has been updated
  • Documentation has been built locally and changes look as expected
• Linting
  • Pre-commit run locally
• Testing
  • Add a comment to the PR titled Testing with the following:
    • Which machines CTest unit tests
      have been run on and indicate that are all passing.
    • The Polaris omega_pr test suite
      has passed, using the Polaris e3sm_submodules/Omega baseline
    • Document machine(s), compiler(s), and the build path(s) used for -p for both the baseline (Polaris e3sm_submodules/Omega) and the PR build
    • Indicate "All tests passed" or document failing tests
    • Document testing used to verify the changes including any tests that are added/modified/impacted.
  • New tests:
    • CTest unit tests for new features have been added per the approved design.

Fixes #347
Fixes #409